<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD><TITLE>gets manual page - Tcl Built-In Commands</TITLE>
<link rel="stylesheet" href="../docs.css" type="text/css" media="all">
</HEAD>
<BODY><H2><a href="../contents.htm">Tcl8.6.11/Tk8.6.11 Documentation</a> <small>&gt;</small> <a href="contents.htm">Tcl Commands</a> <small>&gt;</small> gets</H2>
<H3><A HREF="../UserCmd/contents.htm">Tcl/Tk Applications</A> | <A HREF="../TclCmd/contents.htm">Tcl Commands</A> | <A HREF="../TkCmd/contents.htm">Tk Commands</A> | <A HREF="../ItclCmd/contents.htm">[incr Tcl] Package Commands</A> | <A HREF="../SqliteCmd/contents.htm">SQLite3 Package Commands</A> | <A HREF="../TdbcCmd/contents.htm">TDBC Package Commands</A> | <A HREF="../TdbcmysqlCmd/contents.htm">tdbc::mysql Package Commands</A> | <A HREF="../TdbcodbcCmd/contents.htm">tdbc::odbc Package Commands</A> | <A HREF="../TdbcpostgresCmd/contents.htm">tdbc::postgres Package Commands</A> | <A HREF="../TdbcsqliteCmd/contents.htm">tdbc::sqlite3 Package Commands</A> | <A HREF="../ThreadCmd/contents.htm">Thread Package Commands</A> | <A HREF="../TclLib/contents.htm">Tcl C API</A> | <A HREF="../TkLib/contents.htm">Tk C API</A> | <A HREF="../ItclLib/contents.htm">[incr Tcl] Package C API</A> | <A HREF="../TdbcLib/contents.htm">TDBC Package C API</A></H3>
<H3><A NAME="M2">NAME</A></H3>
gets &mdash; Read a line from a channel
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>gets </B><I>channelId</I> ?<I>varName</I>?<BR>
<H3><A NAME="M4">DESCRIPTION</A></H3>
This command reads the next line from <I>channelId</I>, returns everything
in the line up to (but not including) the end-of-line character(s), and
discards the end-of-line character(s).
<P>
<I>ChannelId</I> must be an identifier for an open channel such as the
Tcl standard input channel (<B><A HREF="../TclLib/GetStdChan.htm">stdin</A></B>), the return value from an
invocation of <B><A HREF="../TclCmd/open.htm">open</A></B> or <B><A HREF="../TclCmd/socket.htm">socket</A></B>, or the result of a channel
creation command provided by a Tcl extension. The channel must have
been opened for input.
<P>
If <I>varName</I> is omitted the line is returned as the result of the
command.
If <I>varName</I> is specified then the line is placed in the variable by
that name and the return value is a count of the number of characters
returned.
<P>
If end of file occurs while scanning for an end of
line, the command returns whatever input is available up to the end of file.
If <I>channelId</I> is in non-blocking mode and there is not a full
line of input available, the command returns an empty string and
does not consume any input.
If <I>varName</I> is specified and an empty string is returned in
<I>varName</I> because of end-of-file or because of insufficient
data in non-blocking mode, then the return count is -1.
Note that if <I>varName</I> is not specified then the end-of-file
and no-full-line-available cases can
produce the same results as if there were an input line consisting
only of the end-of-line character(s).
The <B><A HREF="../TclCmd/eof.htm">eof</A></B> and <B><A HREF="../TclCmd/fblocked.htm">fblocked</A></B> commands can be used to distinguish
these three cases.
<H3><A NAME="M5">EXAMPLE</A></H3>
This example reads a file one line at a time and prints it out with
the current line number attached to the start of each line.
<P>
<PRE>set chan [open &quot;some.file.txt&quot;]
set lineNumber 0
while {[<B>gets</B> $chan line] &gt;= 0} {
    puts &quot;[incr lineNumber]: $line&quot;
}
close $chan</PRE>
<H3><A NAME="M6">SEE ALSO</A></H3>
<B><A HREF="../TclCmd/file.htm">file</A></B>, <B><A HREF="../TclCmd/eof.htm">eof</A></B>, <B><A HREF="../TclCmd/fblocked.htm">fblocked</A></B>, <B><A HREF="../TclLib/StdChannels.htm">Tcl_StandardChannels</A></B>
<H3><A NAME="M7">KEYWORDS</A></H3>
<A href="../Keywords/B.htm#blocking">blocking</A>, <A href="../Keywords/C.htm#channel">channel</A>, <A href="../Keywords/E.htm#end of file">end of file</A>, <A href="../Keywords/E.htm#end of line">end of line</A>, <A href="../Keywords/L.htm#line">line</A>, <A href="../Keywords/N.htm#non-blocking">non-blocking</A>, <A href="../Keywords/R.htm#read">read</A>
<div class="copy">Copyright &copy; 1993 The Regents of the University of California.
<BR>Copyright &copy; 1994-1996 Sun Microsystems, Inc.
</div>
</BODY></HTML>
